<!DOCTYPE html>

<html>
  <head>
    <meta charset="utf-8">
    
    <title>numpy.random.RandomState.hypergeometric &mdash; NumPy v1.18 Manual</title>
    
    <link rel="stylesheet" type="text/css" href="../../../_static/css/spc-bootstrap.css">
    <link rel="stylesheet" type="text/css" href="../../../_static/css/spc-extend.css">
    <link rel="stylesheet" href="../../../_static/scipy.css" type="text/css" >
    <link rel="stylesheet" href="../../../_static/pygments.css" type="text/css" >
    <link rel="stylesheet" href="../../../_static/graphviz.css" type="text/css" >
    
    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
        URL_ROOT:    '../../../',
        VERSION:     '1.18.1',
        COLLAPSE_INDEX: false,
        FILE_SUFFIX: '.html',
        HAS_SOURCE:  false
      };
    </script>
    <script type="text/javascript" src="../../../_static/jquery.js"></script>
    <script type="text/javascript" src="../../../_static/underscore.js"></script>
    <script type="text/javascript" src="../../../_static/doctools.js"></script>
    <script type="text/javascript" src="../../../_static/language_data.js"></script>
    <script type="text/javascript" src="../../../_static/js/copybutton.js"></script>
    <link rel="author" title="About these documents" href="../../../about.html" >
    <link rel="index" title="Index" href="../../../genindex.html" >
    <link rel="search" title="Search" href="../../../search.html" >
    <link rel="top" title="NumPy v1.18 Manual" href="../../../index.html" >
    <link rel="up" title="Legacy Random Generation" href="../legacy.html" >
    <link rel="next" title="numpy.random.RandomState.laplace" href="numpy.random.RandomState.laplace.html" >
    <link rel="prev" title="numpy.random.RandomState.gumbel" href="numpy.random.RandomState.gumbel.html" > 
  </head>
  <body>
<div class="container">
  <div class="top-scipy-org-logo-header" style="background-color: #a2bae8;">
    <a href="../../../index.html">
      <img border=0 alt="NumPy" src="../../../_static/numpy_logo.png"></a>
    </div>
  </div>
</div>


    <div class="container">
      <div class="main">
        
	<div class="row-fluid">
	  <div class="span12">
	    <div class="spc-navbar">
              
    <ul class="nav nav-pills pull-left">
        <li class="active"><a href="https://numpy.org/">NumPy.org</a></li>
        <li class="active"><a href="https://numpy.org/doc">Docs</a></li>
        
        <li class="active"><a href="../../../index.html">NumPy v1.18 Manual</a></li>
        

          <li class="active"><a href="../../index.html" >NumPy Reference</a></li>
          <li class="active"><a href="../../routines.html" >Routines</a></li>
          <li class="active"><a href="../index.html" >Random sampling (<code class="xref py py-mod docutils literal notranslate"><span class="pre">numpy.random</span></code>)</a></li>
          <li class="active"><a href="../legacy.html" accesskey="U">Legacy Random Generation</a></li> 
    </ul>
              
              
    <ul class="nav nav-pills pull-right">
      <li class="active">
        <a href="../../../genindex.html" title="General Index"
           accesskey="I">index</a>
      </li>
      <li class="active">
        <a href="numpy.random.RandomState.laplace.html" title="numpy.random.RandomState.laplace"
           accesskey="N">next</a>
      </li>
      <li class="active">
        <a href="numpy.random.RandomState.gumbel.html" title="numpy.random.RandomState.gumbel"
           accesskey="P">previous</a>
      </li>
    </ul>
              
	    </div>
	  </div>
	</div>
        

	<div class="row-fluid">
      <div class="spc-rightsidebar span3">
        <div class="sphinxsidebarwrapper">
  <h4>Previous topic</h4>
  <p class="topless"><a href="numpy.random.RandomState.gumbel.html"
                        title="previous chapter">numpy.random.RandomState.gumbel</a></p>
  <h4>Next topic</h4>
  <p class="topless"><a href="numpy.random.RandomState.laplace.html"
                        title="next chapter">numpy.random.RandomState.laplace</a></p>
<div id="searchbox" style="display: none" role="search">
  <h4>Quick search</h4>
    <div>
    <form class="search" action="../../../search.html" method="get">
      <input type="text" style="width: inherit;" name="q" />
      <input type="submit" value="search" />
      <input type="hidden" name="check_keywords" value="yes" />
      <input type="hidden" name="area" value="default" />
    </form>
    </div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
        </div>
      </div>
          <div class="span9">
            
        <div class="bodywrapper">
          <div class="body" id="spc-section-body">
            
  <div class="section" id="numpy-random-randomstate-hypergeometric">
<h1>numpy.random.RandomState.hypergeometric<a class="headerlink" href="#numpy-random-randomstate-hypergeometric" title="Permalink to this headline">¶</a></h1>
<p>method</p>
<dl class="method">
<dt id="numpy.random.RandomState.hypergeometric">
<code class="sig-prename descclassname">RandomState.</code><code class="sig-name descname">hypergeometric</code><span class="sig-paren">(</span><em class="sig-param">ngood</em>, <em class="sig-param">nbad</em>, <em class="sig-param">nsample</em>, <em class="sig-param">size=None</em><span class="sig-paren">)</span><a class="headerlink" href="#numpy.random.RandomState.hypergeometric" title="Permalink to this definition">¶</a></dt>
<dd><p>Draw samples from a Hypergeometric distribution.</p>
<p>Samples are drawn from a hypergeometric distribution with specified
parameters, <em class="xref py py-obj">ngood</em> (ways to make a good selection), <em class="xref py py-obj">nbad</em> (ways to make
a bad selection), and <em class="xref py py-obj">nsample</em> (number of items sampled, which is less
than or equal to the sum <code class="docutils literal notranslate"><span class="pre">ngood</span> <span class="pre">+</span> <span class="pre">nbad</span></code>).</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>New code should use the <code class="docutils literal notranslate"><span class="pre">hypergeometric</span></code> method of a <code class="docutils literal notranslate"><span class="pre">default_rng()</span></code>
instance instead; see <em class="xref py py-obj">random-quick-start</em>.</p>
</div>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><dl class="simple">
<dt><strong>ngood</strong><span class="classifier">int or array_like of ints</span></dt><dd><p>Number of ways to make a good selection.  Must be nonnegative.</p>
</dd>
<dt><strong>nbad</strong><span class="classifier">int or array_like of ints</span></dt><dd><p>Number of ways to make a bad selection.  Must be nonnegative.</p>
</dd>
<dt><strong>nsample</strong><span class="classifier">int or array_like of ints</span></dt><dd><p>Number of items sampled.  Must be at least 1 and at most
<code class="docutils literal notranslate"><span class="pre">ngood</span> <span class="pre">+</span> <span class="pre">nbad</span></code>.</p>
</dd>
<dt><strong>size</strong><span class="classifier">int or tuple of ints, optional</span></dt><dd><p>Output shape.  If the given shape is, e.g., <code class="docutils literal notranslate"><span class="pre">(m,</span> <span class="pre">n,</span> <span class="pre">k)</span></code>, then
<code class="docutils literal notranslate"><span class="pre">m</span> <span class="pre">*</span> <span class="pre">n</span> <span class="pre">*</span> <span class="pre">k</span></code> samples are drawn.  If size is <code class="docutils literal notranslate"><span class="pre">None</span></code> (default),
a single value is returned if <em class="xref py py-obj">ngood</em>, <em class="xref py py-obj">nbad</em>, and <em class="xref py py-obj">nsample</em>
are all scalars.  Otherwise, <code class="docutils literal notranslate"><span class="pre">np.broadcast(ngood,</span> <span class="pre">nbad,</span> <span class="pre">nsample).size</span></code>
samples are drawn.</p>
</dd>
</dl>
</dd>
<dt class="field-even">Returns</dt>
<dd class="field-even"><dl class="simple">
<dt><strong>out</strong><span class="classifier">ndarray or scalar</span></dt><dd><p>Drawn samples from the parameterized hypergeometric distribution. Each
sample is the number of good items within a randomly selected subset of
size <em class="xref py py-obj">nsample</em> taken from a set of <em class="xref py py-obj">ngood</em> good items and <em class="xref py py-obj">nbad</em> bad items.</p>
</dd>
</dl>
</dd>
</dl>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<dl class="simple">
<dt><a class="reference external" href="https://docs.scipy.org/doc/scipy/reference/generated/scipy.stats.hypergeom.html#scipy.stats.hypergeom" title="(in SciPy v1.4.1)"><code class="xref py py-obj docutils literal notranslate"><span class="pre">scipy.stats.hypergeom</span></code></a></dt><dd><p>probability density function, distribution or cumulative density function, etc.</p>
</dd>
<dt><a class="reference internal" href="numpy.random.Generator.hypergeometric.html#numpy.random.Generator.hypergeometric" title="numpy.random.Generator.hypergeometric"><code class="xref py py-obj docutils literal notranslate"><span class="pre">Generator.hypergeometric</span></code></a></dt><dd><p>which should be used for new code.</p>
</dd>
</dl>
</div>
<p class="rubric">Notes</p>
<p>The probability density for the Hypergeometric distribution is</p>
<div class="math">
<p><img src="../../../_images/math/07d49380b46a8e69eb8b30fd48a685ddb86a4e84.svg" alt="P(x) = \frac{\binom{g}{x}\binom{b}{n-x}}{\binom{g+b}{n}},"/></p>
</div><p>where <img class="math" src="../../../_images/math/fd3cbdb9eaf1031b7698101493d53e798cb1abe2.svg" alt="0 \le x \le n"/> and <img class="math" src="../../../_images/math/8c3ea49082a625f01a58b27b6829f4583398618e.svg" alt="n-b \le x \le g"/></p>
<p>for P(x) the probability of <code class="docutils literal notranslate"><span class="pre">x</span></code> good results in the drawn sample,
g = <em class="xref py py-obj">ngood</em>, b = <em class="xref py py-obj">nbad</em>, and n = <em class="xref py py-obj">nsample</em>.</p>
<p>Consider an urn with black and white marbles in it, <em class="xref py py-obj">ngood</em> of them
are black and <em class="xref py py-obj">nbad</em> are white. If you draw <em class="xref py py-obj">nsample</em> balls without
replacement, then the hypergeometric distribution describes the
distribution of black balls in the drawn sample.</p>
<p>Note that this distribution is very similar to the binomial
distribution, except that in this case, samples are drawn without
replacement, whereas in the Binomial case samples are drawn with
replacement (or the sample space is infinite). As the sample space
becomes large, this distribution approaches the binomial.</p>
<p class="rubric">References</p>
<dl class="citation">
<dt class="label" id="r1f2e8fcacf2b-1"><span class="brackets">1</span></dt>
<dd><p>Lentner, Marvin, “Elementary Applied Statistics”, Bogden
and Quigley, 1972.</p>
</dd>
<dt class="label" id="r1f2e8fcacf2b-2"><span class="brackets">2</span></dt>
<dd><p>Weisstein, Eric W. “Hypergeometric Distribution.” From
MathWorld–A Wolfram Web Resource.
<a class="reference external" href="http://mathworld.wolfram.com/HypergeometricDistribution.html">http://mathworld.wolfram.com/HypergeometricDistribution.html</a></p>
</dd>
<dt class="label" id="r1f2e8fcacf2b-3"><span class="brackets">3</span></dt>
<dd><p>Wikipedia, “Hypergeometric distribution”,
<a class="reference external" href="https://en.wikipedia.org/wiki/Hypergeometric_distribution">https://en.wikipedia.org/wiki/Hypergeometric_distribution</a></p>
</dd>
</dl>
<p class="rubric">Examples</p>
<p>Draw samples from the distribution:</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">ngood</span><span class="p">,</span> <span class="n">nbad</span><span class="p">,</span> <span class="n">nsamp</span> <span class="o">=</span> <span class="mi">100</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">10</span>
<span class="go"># number of good, number of bad, and number of samples</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">s</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">random</span><span class="o">.</span><span class="n">hypergeometric</span><span class="p">(</span><span class="n">ngood</span><span class="p">,</span> <span class="n">nbad</span><span class="p">,</span> <span class="n">nsamp</span><span class="p">,</span> <span class="mi">1000</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">matplotlib.pyplot</span> <span class="kn">import</span> <span class="n">hist</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">hist</span><span class="p">(</span><span class="n">s</span><span class="p">)</span>
<span class="go">#   note that it is very unlikely to grab both bad items</span>
</pre></div>
</div>
<p>Suppose you have an urn with 15 white and 15 black marbles.
If you pull 15 marbles at random, how likely is it that
12 or more of them are one color?</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">s</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">random</span><span class="o">.</span><span class="n">hypergeometric</span><span class="p">(</span><span class="mi">15</span><span class="p">,</span> <span class="mi">15</span><span class="p">,</span> <span class="mi">15</span><span class="p">,</span> <span class="mi">100000</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="nb">sum</span><span class="p">(</span><span class="n">s</span><span class="o">&gt;=</span><span class="mi">12</span><span class="p">)</span><span class="o">/</span><span class="mf">100000.</span> <span class="o">+</span> <span class="nb">sum</span><span class="p">(</span><span class="n">s</span><span class="o">&lt;=</span><span class="mi">3</span><span class="p">)</span><span class="o">/</span><span class="mf">100000.</span>
<span class="go">#   answer = 0.003 ... pretty unlikely!</span>
</pre></div>
</div>
</dd></dl>

</div>


          </div>
        </div>
          </div>
        </div>
      </div>
    </div>

    <div class="container container-navbar-bottom">
      <div class="spc-navbar">
        
      </div>
    </div>
    <div class="container">
    <div class="footer">
    <div class="row-fluid">
    <ul class="inline pull-left">
      <li>
        &copy; Copyright 2008-2019, The SciPy community.
      </li>
      <li>
      Last updated on Feb 20, 2020.
      </li>
      <li>
      Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 2.4.2.
      </li>
    </ul>
    </div>
    </div>
    </div>
  </body>
</html>